home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 (Alt) / MACD 5.bin / workbench / libs / gadutil.lha / GadUtil / docs / GadUtil.manual < prev    next >
Encoding:
Text File  |  1996-04-29  |  10.6 KB  |  234 lines
  1. *-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
  2. |                                                                           |
  3. *                      Gadutil.library version 37.0                         *
  4. |                                                                           |
  5. *           Copyright © 1994-96 by Staffan Hämälä and P-O Yliniemi          *
  6. |                                                                           |
  7. *-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
  8.  
  9. GadUtil is another gui library which main goal was to make it easy to create
  10. font sensitive user interfaces.  The library has grown away from this main
  11. goal, and become another useful-routine-library.
  12.  
  13. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  14.   Distribution:
  15.  
  16.      1) Distribution of this library is allowed in two ways:
  17.           ¹) Only the .library file(s)
  18.           ²) The complete distribution
  19.  
  20.      2) Programmers of totally free software can use and distribute this
  21.         library for free.
  22.  
  23.      3) Programmers of Shareware, Licensware, commercial products and other
  24.         programs that the programmer get any kind of profit from shall send
  25.         a fully working (and registered) copy of the program and its docs to
  26.         us. All larger updates of the program should also be sent to us.
  27.           
  28.      4) Programmers of non-free software not covered by 1) and 2) (my Diskware
  29.         concept belongs to this group) shall be treated as in 3) (a fully
  30.         working and registered copy...).
  31.  
  32.      5) All programs (except commercial products in some cases) must state
  33.         that gadutil.library is used. This may be done in either the About
  34.         requester or in the documentation, but best of all in both places.
  35.  
  36.         Demonstration programs for gadutil.library (that includes the full
  37.         source) may be distributed without this note.
  38.  
  39.         Example for inclusion in About requester:
  40.  
  41.              "This program uses gadutil.library, which
  42.               is Copyright © 1994-1996 by P-O Yliniemi
  43.               and Staffan Hämälä."
  44.  
  45.      6) All localized programs that uses this library should include the
  46.         .ct file(s) to allow anyone to translate that program into their
  47.         own language.
  48.  
  49.  
  50. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  51. Below is a list of some of the main functions covered by this library.
  52.  
  53. * FAST (NO OR VERY SMALL DIFFERENCE AGAINST GADTOOLS) AND SMALL (ABOUT 10k).
  54.   WRITTEN IN ASSEMBLY LANGUAGE. NO F*CKING 'C' or any other slow language!
  55.  
  56. * Font adaptive. Use any of the system fonts and most other fonts for
  57.   gadgets, texts and menus. All gadgets are placed relative to each
  58.   other, but can be placed at absolute positions (needed for the first
  59.   gadget).
  60.  
  61. * No need to use GIMMEZEROZERO windows, as this is automatically handled
  62.   by the library. If you specify a gadget position of 10,10 the gadget
  63.   will be placed at 10,10 within the window's border.
  64.  
  65. * Localized. It is really easy to localize all your (new) programs by
  66.   using this library. Functions and macros for creating localized menus
  67.   are supplied.
  68.  
  69. * Both assembly and 'C' language support. This is one of the things that is
  70.   missing in most of the other gui libraries. Some extra macros are defined
  71.   for assembly language users, and will make the gadget and menu creating
  72.   process even more easy.
  73.  
  74. * All GadTools gadgets are supported. Some extra functions are provided
  75.   for ListViews. BUTTON_KIND (and IMAGE_KIND) gadgets have some extra tags,
  76.   including a toggle-select option.
  77.  
  78.   4 extended gadget types are handled by the library:
  79.     
  80.     · FILE_KIND     - gadget for selecting a file.
  81.  
  82.     · DRAWER_KIND   - gadget for selecting a drawer. Most programs also
  83.                       use this gadget for file selection.
  84.  
  85.     · IMAGE_KIND    - uses an intuition image for the gadget. Can use
  86.                       different images for selected and non-selected state.
  87.  
  88.     · BEVELBOX_KIND - gadtools bevelboxes, with some extensions. All
  89.                       gadtools bevelboxes are supported (even with v37).
  90.                       Extensions allows text to be placed above, in or below
  91.                       the upper line of the box. All kinds can be inverted.
  92.  
  93.                       New for v36.52: Bevelbox text placement extended.
  94.                       3 new placements available together with the old
  95.                       ones: centered, left adjusted & right adjusted.
  96.  
  97.                       BFT_BUTTON   - GT v37 BUTTON_KIND border
  98.                       BFT_RIDGE    - GT v37 STRING_KIND border
  99.                       BFT_DROPBOX  - GT v39 BBFT_ICONDROPBOX border
  100.                       BFT_HORIZBAR - A horizontal shadowed line
  101.                       BFT_VERTBAR  - A vertical shadowed line
  102.  
  103.                       This makes it a total of 100 bevel box types. The bevel
  104.                       boxes are treated as gadgets by the library, and you
  105.                       can obtain the structure for the bevelbox in the same
  106.                       way as you get the gadget pointer.
  107.  
  108.     · PROGRESS_KIND - Gadget that shows a progress indicator, like the ones
  109.                       that can be found in disk-copiers, formatting programs,
  110.                       install-scripts etc. It's very easy to set the gadget
  111.                       up, and then updating it via a library function.
  112.  
  113. * A new OpenFont() (graphics.library and diskfont.library replacement).
  114.   This function will open any font (from RAM, ROM or load it from disk).
  115.  
  116. * Functions for listviews include adding nodes (memory for the string is
  117.   allocated by the function), counting nodes, getting node pointers, clearing
  118.   a listview, attach and detach lists, moving nodes up and down.
  119.  
  120. * No need to open gadtools.library anymore, since all gadtools functions are
  121.   provided through this library. Some (the most useable) functions from
  122.   locale library are also provided by gadutil.
  123.  
  124. * Many libraries are opened through gadutil.library, and these library bases
  125.   are available for your own use (you don't have to open or close some libs).
  126.  
  127. * All gadgets are created using tag lists. Every next gadget will use the
  128.   previous gadgets values as defaults. Only one call to the gadget making
  129.   routine is needed for every gadget list.
  130.  
  131. * All gadgets can have their own hotkey. No extra work is needed by the
  132.   programmer (only one extra tag).
  133.  
  134. * Distributed with lots of examples, mostly in assembly language, but also
  135.   in 'C'.
  136.  
  137. * Other functions include:
  138.  
  139.     · Status change for toggle select buttons.
  140.  
  141.     · String change for STRING and TEXT_KIND gadgets.
  142.  
  143.     · Disable functions for gadgets that support the GA_Disabled tag.
  144.  
  145.     · Routines to set up a busy-pointer (available for both v37 and v39).
  146.       These routines also blocks the input to the main window of the program.
  147.  
  148.     · Routine to check if the mouse pointer is within a gadgets box. Useful
  149.       for mouse-position sensitive appwindows.
  150.  
  151.     · Bevelbox and window refreshing functions.
  152.  
  153. * FAST (NO OR VERY SMALL DIFFERENCE AGAINST GADTOOLS) AND SMALL (ABOUT 10k).
  154.   WRITTEN IN ASSEMBLY LANGUAGE. NO F*CKING 'C' or any other slow language!
  155.  
  156.  
  157. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  158. A little of the history behind this program:
  159.  
  160. Everybody who have tried to do a program with a nice GUI have almost certainly
  161. come across the problem; how to adjust the program based on the font that user
  162. has selected.  It began as a little test program that should be able to adjust
  163. itself, but I soon realized that it wasn't that easy (as I had thought).
  164.  
  165. I  was  almost  finished with a working version of the program when I got some
  166. other programs/libraries that did something similar.
  167.  
  168. The first program I got was MUI (Magical User Interface).  It wasn't that bad,
  169. but it was big (170k) and it was slow.
  170.  
  171. Another  program  was gadoutline.library, it wasn't exactly like I would want,
  172. and it was quite big (60k).
  173.  
  174. Then,  I  came  across  the  program that I liked the most:  GadLayout 1.5.  I
  175. changed  one  of  my  programs,  so that it would use GadLayout, but it didn't
  176. work.   I  think  that  the problem was that my assembler didn't work with the
  177. object file for GadLayout (I had never tried that before).
  178.  
  179. When  GadLayout  didn't  work  for  me  I continued with my own project, but I
  180. changed  it  a bit, because I liked the way GadLayout used tags.  So I changed
  181. my  program , so that it used tags instead of my own gadget structure.  I also
  182. tried  to make the tags work in a similar way as GadLayout's tags, I also used
  183. similar names for the tags (mainly so that I didn't need to change the program
  184. I had adjusted to GadLayout so much.
  185.  
  186. After  that the first beta version of the program was ready, a friend of mine,
  187. P-O, also started working on the project.  We decided to make the program into
  188. a  shared library, so that all programs could use it without having to include
  189. it in the executable file.  The library was named GadUtil.
  190.  
  191. After  that  moment  the  library  has  grown  quite a lot, with new tags, new
  192. functions, a lot of enhancements and bugfixes.  Now the library contains about
  193. 47  functions, and has quite a lot of tags.  Another feature of the library is
  194. that  it  has some new gadget kinds, like a progress indicator, image gadgets,
  195. drawer  gadgets  etc.  It is also very easy to add hotkeys and localization to
  196. your programs when using gadutil.library.
  197.  
  198.  
  199. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  200. Special thanx must go to:
  201.  
  202.  · Amiga Inc. / Commodore / Escom / Amiga Technologies / Viscorp
  203.    - For making everything possible
  204.  
  205.  · Timothy J. Aston
  206.    - For the inspiration, GadLayout 1.5 (a link library for 'C' programmers)
  207.  
  208.  · Nico Max
  209.    - For forcing us to release gadutil a bit sooner than it was meant to.
  210.  
  211.  · Lukasz Szelag
  212.    - For the first, and the three following bug reports
  213.    - For ideas about some new constants for the include files
  214.  
  215.  · Morten Amundsen
  216.    - For the suggestion of two new tags (so far)
  217.  
  218.  
  219.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  220.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  221.         Per-Olof Yliniemi                           Staffan Hämälä
  222.         Box 78                                      Pellovägen 268
  223.         S-980 61 Tärendö                            S-957 93 Pello
  224.         SWEDEN                                      SWEDEN
  225.  
  226.         email:                                      email:
  227.           peoyli@pluggnet.se                          staham@pluggnet.se
  228.  
  229.         phone:
  230.           +46-(0)978-20522
  231.  
  232.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  233.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  234.